<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Message</title>
<meta http-equiv="Content-Type" Content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../styles/styles.css">
<script language="javascript" src='../links.js' type="text/javascript"></script>
</head>

<body>

<h1>Message</h1>
<div class=navbar>
<a href="../index.html">main</a> |
<a href="index.html">service functions</a><br>
</div>

<div class=shortdescr>
The <dfn>Message</dfn> function shows a message.
</div>

<pre class=syntax>
int WINAPI Message(
  int PluginNumber,
  DWORD Flags,
  const char *HelpTopic,
  const char * const *Items,
  int ItemsNumber,
  int ButtonsNumber
);
</pre>
<h3>Parameters</h3>
<div class=descr>

    <div class=dfn>PluginNumber</div>
    <div class=dfndescr>Number of the plugin module. It is passed to the plugin in the
      <a href="../exported_functions/setstartupinfo.html">SetStartupInfo</a> function.
    </div>

    <div class=dfn>Flags</div>
    <div class=dfndescr>Can be a combination of the following values (<a name="FARMESSAGEFLAGS">FARMESSAGEFLAGS</a> enum):
<table class="cont">
<tr class="cont"><th class="cont" width="40%">Flag</th><th class="cont" width="60%">Description</th></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_WARNING">FMSG_WARNING</a></td>
        <td class="cont" width="60%">Warning message colors are used (white text on red background by default).
        </td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_ERRORTYPE">FMSG_ERRORTYPE</a></td>
        <td class="cont" width="60%">If error type returned by
          <a href="win32/GetLastError">GetLastError</a>
          <a href="../defs/winerror.html">is known to FAR</a> or Windows,
          the error description will be shown in the first message line.
          In that case, the text given by the plugin will be displayed below the error description.
        </td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_KEEPBACKGROUND">FMSG_KEEPBACKGROUND</a></td>
        <td class="cont" width="60%">Do not redraw the message background.
        </td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_DOWN">FMSG_DOWN</a></td>
        <td class="cont" width="60%">Display the message two lines lower than usual.
         </td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_LEFTALIGN">FMSG_LEFTALIGN</a></td>
        <td class="cont" width="60%">Left align the message lines instead of centering them.
        </td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_ALLINONE">FMSG_ALLINONE</a></td>
        <td class="cont" width="60%">
          In this case the <var>Items</var> parameter is not an array of string pointers.
          <dfn class=alert3>Instead it points to a single string</dfn> in which the lines of the
          message are separated by the newline character <code>'\n'</code>.
        <p>Minimal number of lines is - 2 - a title and one message line.
        <p>If this flag is specified the <var>ItemsNumber</var> parameter is ignored and the number
        of lines shown is calculated automatically (taking into account the button flags -FMSG_MB_*).
        <p>To suppress title output when this flag is specified, start the line with a
        <code>'\n'</code> character.
        </td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_OK">FMSG_MB_OK</a></td>
        <td class="cont" width="60%">Additional button: &lt;Ok&gt;</td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_OKCANCEL">FMSG_MB_OKCANCEL</a></td>
        <td class="cont" width="60%">Additional buttons: &lt;Ok&gt; and &lt;Cancel&gt;</td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_ABORTRETRYIGNORE">FMSG_MB_ABORTRETRYIGNORE</a></td>
        <td class="cont" width="60%">Additional buttons: &lt;Abort&gt;, &lt;Retry&gt; and &lt;Ignore&gt;</td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_YESNO">FMSG_MB_YESNO</a></td>
        <td class="cont" width="60%">Additional buttons: &lt;Yes&gt; and &lt;No&gt;</td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_YESNOCANCEL">FMSG_MB_YESNOCANCEL</a></td>
        <td class="cont" width="60%">Additional buttons: &lt;Yes&gt;, &lt;No&gt; and &lt;Cancel&gt;</td></tr>

        <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_RETRYCANCEL">FMSG_MB_RETRYCANCEL</a></td>
        <td class="cont" width="60%">Additional buttons: &lt;Retry&gt; and &lt;Cancel&gt;</td></tr>

</table>
      </div>

    <div class=dfn>HelpTopic</div>
    <div class=dfndescr>The <a href="../language/helptopic.html">help topic</a>
      associated with the message.Set to <code>NULL</code> if help is not used.
    </div>

    <div class=dfn>Items</div>
    <div class=dfndescr>Address of an array of pointers to null-terminated text strings. The first
      string is the message title, the last <var>ButtonsNumber</var> strings are buttons, and all other strings
      belong to the message body.<br>
      To draw a single border line start the string with a character with code 1 (\x001).<br>
      To draw a double border line start the string with a character with code 2 (\x002).<br>
      See also the description of the flag <a href="#FMSG_ALLINONE">FMSG_ALLINONE</a></div>
    <div class=dfn>ItemsNumber</div>
    <div class=dfndescr>Number of strings in the array passed in the <var>Items</var> parameter.
      Minimal values - 2 lines.</div>
    <div class=dfn>ButtonsNumber</div>
    <div class=dfndescr>Number of strings which are shown as buttons. If one of the FMSG_MB_* flags
      is set, this value is ignored.
    </div>

</div>

<h3>Return value</h3>
<div class=descr>
This function returns either -1, if the user cancelled the message (or the sysrem could not
allocate enough memory for internal buffers), or the number of the selected button (for the first
button 0 is returned, for the second 1 is returned, and so on).
</div>

<h3>Remarks</h3>
<div class=descr>
<ol>
<li>In FAR Manager versions up to (and including) 1.70 beta 4 the maximum number of items in a message (including the buttons) was limited to 13.
<li>If <var>ButtonsNumber</var> is zero and none of the FMSG_MB_* flags is set
    the plugin <u>should</u> restore the screen either by using
    <a href="restorescreen.html">RestoreScreen</a> or in any other way when the message output is
    no longer necessary
<li>If <var>ButtonsNumber</var>  is not equal to zero, the screen will be restored by FAR.
<li>If <var>Items</var> is <code>NULL</code> or the total number of items is less than 2, the
    message is not shown.
<li>When FMSG_MB_* button flags are specified the <var>ButtonsNumber</var> parameter is ignored.
<li>It is possible to specify hotkeys for buttons.
<li>When using the FMSG_ALLINONE flag you need to do an explicit typecast to achieve error free
compilation:
<table border=0><tr>
<td>
<pre class=code>Info.Message(Info.ModuleNumber,
  FMSG_ALLINONE|FMSG_MB_OKCANCEL,
  "HelpTopic",
  <b>(const char * const *)</b>"Title\nItem1\nItem2\nItem3",
  0,0);</pre>
or
<pre class=code>
const char *Msg="Title\nItem1\nItem2\nItem3\nOk\nCancel";
Info.Message(Info.ModuleNumber,
  FMSG_ALLINONE,
  "HelpTopic",
  <b>(const char * const *)</b>Msg,
  0,2);</pre>
</td>
<td><img src="../../images/msg1.gif" width="110" height="96"></td>
</tr></table>

</ol>
</div>

<h3>Example</h3>
<div class=descr>
  The following function displays a file deletion confirmation dialog:<br>
  <img src="../../images/message.gif" width="234" height="63" alt="file deletion confirmation dialog">
<pre class=code>BOOL IsDeleted(char *filename)
{
  const char *Msg[5];

  Msg[0]=GetMsg(MTitle);       // message title
  Msg[1]=GetMsg(MIsDeleted);   // message body
  Msg[2]=filename;
  Msg[3]=GetMsg(MDelete);      // last ButtonsNumber (2) strings are buttons
  Msg[4]=GetMsg(MCancel);

  return Info.Message(Info.ModuleNumber,
               0,
               "DeleteFile",
               Msg,
               sizeof(Msg)/sizeof(Msg[0]),
               2) == 0;
}</pre>

Info is defined as a global variable:

<pre class=code>struct <a href="../structures/pluginstartupinfo.html">PluginStartupInfo</a> Info;</pre>

...and is initialized in the <a href="../exported_functions/setstartupinfo.html">SetStartupInfo</a> function:

<pre class=code>void WINAPI _export SetStartupInfo(struct PluginStartupInfo *Info)
{
  ...
  ::Info=*Info;
  ...
}</pre>

</div>

<div class=see>See also:</div><div class=seecont>
<a href="../dialogapi/dialog.html">Dialog</a>
</div>

</body>
</html>
